/*
 * Copyright the original author or authors.
 * 
 * Licensed under the MOZILLA PUBLIC LICENSE, Version 1.1 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.mozilla.org/MPL/MPL-1.1.html
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
import com.bourre.structures.Range;
import com.kairos.engine.RTEvent;
	
/**
 * A {@code MonitorField} object represent a value witch can be displayed
 * in the {@code Monitor} object.
 * 
 * <p>Monitors fields can be labels, curve in the graph or both according to
 * {@code isCurve()} and {@code isLabel()} returned value.</p>
 * 
 * @author  Cédric Néhémie
 * @see		Monitor
 */
interface com.kairos.utils.monitor.MonitorField
{
	/**
	 * Returns the current value of the field formatted as a {@code String}.
	 * 
	 * <p>If the value have a specific unit, the formatted string
	 * will include it.</p>
	 * 
	 * @return {@code String} of the formatted value.
	 */
	function getFormattedValue () : String;
	
	/**
	 * Defines the color of the current field.
	 * 
	 * <p>The color have to be defined before its add to the {@code Monitor}
	 * otherwise the modification isn't considered.</p>
	 * 
	 * <p>Colors are described with ARGB hexadecimal value such
	 * {@code 0xaarrggbb}.</p>
	 * 
	 * @param	col	{@code Number} color for the field.
	 */
	function setColor( col : Number ) : Void;
	
	/**
	 * Returns the color that the {@code Monitor} will use to create
	 * the field label and the field curve.
	 * 
	 * <p>Colors are described with ARGB hexadecimal value such
	 * {@code 0xaarrggbb}.</p>
	 * 
	 * @return 	{@code Number} color of the field.
	 */
	function getColor():Number;
	
	/**
	 * Returns the range between the last value and the current value
	 * of the field in the display bitmap coordinates.
	 * 
	 * <p>The range contained values in pixels according to the
	 * graph's bitmap height passed to this object when added
	 * to the {@code Monitor}. For example, for a monitor's
	 * bitmap with a height of 100, display range from 50 to 150,
	 * value of 100 and last value of 75 the method have to
	 * return a range from 75 to 50. The example below show a basic
	 * implementation of the {@code getDifference} method.</p>
	 * 
	 * <code>public function getDifference () : Range
	 * {
	 * 	return new Range ( _getDisplayValue( _nLastValue ), _getDisplayValue( _nValue ) );
	 * }
	 * 
	 * protected function _getDisplayValue ( value : Number ) : Number
	 * {
	 * 	return _nBitmapHeight - Math.floor( ( ( value - _oDisplayRange.min ) / _oDisplayRange.max ) * _nBitmapHeight );
	 * }
	 * </code>
	 * 
	 * <p>In that example the conversion of a value in the display
	 * bitmap coordinates is performed by a protected method called
	 * {@code _getDisplayValue}.</p>
	 * 
	 * @return {@code Range} of value variations.
	 */
	function getDifference() : Range;
	
	/**
	 * Defines the display values range for the field. All values out
	 * of that range isn't displayed in the graph.</p>
	 * 
	 * <p>That range have to be used to compute the {@code getDifference}
	 * return value.</p>
	 * 
	 * @param	r	{@code Range} of displayed values.
	 */
	function setDisplayRange ( r : Range ) : Void;
	
	/**
	 * Defines the height of the display area. That value is set
	 * by the {@code Monitor} when the object is added to it.
	 * 
	 * <p>That value have to be used to compute the {@code getDifference}
	 * return value.</p>
	 * 
	 * @param	n	{@code Number} of the graph's bitmap height.
	 */
	function setDisplayHeight( n:Number ) : Void;
	/**
	 * Returns the name of the current field witch the {@code Monitor}
	 * will use as label for the field.
	 * 
	 * <p>As in general we used to display the smallest monitor as possible, 
	 * try to set a small and explicit label. The monitor will allways adjust
	 * the size of the monitor on the bitmap rather than on the labels so
	 * textfields will crop the text if it's longer than the allowed size.</p>
	 * 
	 * @return {@code String} name of the field
	 */
	function getName() : String;
	
	/**
	 * Called by the {@code Monitor} on each frame of the
	 * animation.
	 * 
	 * <p>In that method the object set the last value and register
	 * its current value from its source. The example below show how
	 * to simply implements the {@code registerValue} method.</p>
	 * 
	 * <code>public function registerValue( e : RTEvent ) : void
	 * {
	 * 	_nLastValue = _nValue;
	 * 	_nValue = theTargetObject.theTargetProperty;
	 * }
	 * </code>
	 * 
	 * <p>Its important to also register the last value in the same time,
	 * if ommitted the monitor cannot draw the line, it can only draw
	 * a single pixel for the sole value.</p>
	 * 
	 * @param 	e	The RTEvent dispatched by the {@code RTBeacon}.
	 */
	function registerValue( e : RTEvent) : Void;
	
	/**
	 * Returns {@code true} if the field can be displayed as curve
	 * in the graph, {@code false} otherwise.
	 * 
	 * @return {@code true} if the field is a curve in the graph.
	 */
	function isCurve() : Boolean;
	
	/**
	 * Returns {@code true} if the field can be displayed as label
	 * in the monitor, {@code false} otherwise.
	 * 
	 * @return {@code true} if the field have a label in the monitor.
	 */
	function isLabel () : Boolean;
	
	/**
	 * Indicates if field must be displayed ( calculated ) in the graph 
	 * view.
	 * 
	 * @param b {@code true} to display the field in the graph.
	 */
	function setEnabled( b : Boolean ) : Void;
	
	/**
	 * Returns {@code true} if the field is enabled ( can be displayed in 
	 * the graph ).
	 * 
	 * @return {@code true} if the field can be drawn in the graph.
	 */
	function isEnabled () : Boolean;
	
}
